Authorization

In previous versions of Itential Automation Platform (IAP), users and groups had their own menu option. IAP now has a new user interface (UI) to administer users, groups, and roles. Users and groups are contained, along with a new UI for role configuration, in the Authorization Manager.

Terminology

Various terms related to IAP users, groups, and roles are defined in the following table.

Term	Definition
User	An entity that can perform specific actions within multiple IAP applications based on group associations.
Group	A collection of roles that can be assigned to a user.
Role	A collection of granular level privileges that can be assigned to groups.
Privilege	Permission granted to an API and a View.
Provenance	The source of a group; where it was learned. For external groups, this is set to the IAP AAA adapter ID. For IAP groups, it is not set.

To access Authorization Manager, navigate to Settings > Authorization

Networking Requirements

Network connectivity is required between NSO and IAP (typically port 3000) for use with the External Authentication script.

Users

A user is an entity that comes from an eternal AAA System such as LDAP. Users may be a member of any number of groups and through group membership may be assigned any number of roles.

Itential Automation Platform (IAP) provides the ability to assign roles directly to users. Also, with IAP groups, administrators are able to manage user membership.

All operations within IAP are associated with a user. User roles, whether directly assigned or inherited from a group, determine what the user can see and do within IAP. The final permission set of a user will be a combination of permissions granted to all the roles assigned to the user, or to any groups in which the user is a member.

Managing Users

Users are accounts from an external system. Therefore, it is not possible to create a new user within IAP. Instead, IAP will create the user record when someone has successfully logged in using the user’s AAA system credentials.

Use Authorization Manager to see a list of users IAP has encountered and to manage their permissions.

1. Login to IAP as Administrator (a user with the Pronghorn.admin Role).
2. Navigate to Settings > Authorization.
3. Select the Users tab.
4. Locate the User in the list. Optionally filter the list by typing in the Search Users field and pressing Enter, or clicking the search icon.
5. Select the appropriate user from the list to view or edit.
6. Edit attributes, as desired.
7. Edit Roles and Groups, as desired.
8. Click Save to finalize changes.

Roles assigned by groups are greyed out (disabled). This indicates the assignment is inherited.

Configuring Role Assignments for Users

There are two ways to assign users to roles:

• Directly
• By Group membership

To assign roles directly to a User:

1. Select the Roles tab.
2. Locate the Role you wish to assign.
   • Filter the list by typing in the column header text box.
3. Add or Remove a Role assignment using the checkbox.

Roles assigned by Groups are greyed out (disabled). This indicates the assignment is inherited.

Configuring Group Membership for Users

External group memberships for users are managed by the external AAA system and cannot be edited in IAP. A user may only be added or removed from IAP Groups within Authorization Manager. Addition or removal of AAA groups must be performed in the AAA system and will be noticed by IAP the next time the user logs in.

To change the IAP Groups to which a user belongs:

1. Click the Groups tab.
2. Find the Group in the list.
   • Filter the list by typing in the column header textbox.
3. Add or Remove the Group membership using the checkbox.

AAA-managed group memberships will be greyed out (disabled), indicating the membership is not editable in IAP.

Groups

This section captures how users and groups are created and assigned in 2018.3 IAP. Group management and configuration is also explained.

• Users are assigned to External Groups within the external AAA system. Users cannot be assigned to External Groups using IAP.
• An External Group is an entity (account) that comes from an external AAA System such as LDAP. An External Group cannot be created within IAP.
• An IAP Group is an entity created within the IAP system. Users are assigned to IAP Groups through Authorization Manager.

Note: If User1 is a member of Group1 and starts a job, and User2 is not a member of Group1, then User2 will not be able to see the job.

Managing Groups

External groups cannot be created within IAP. Instead, IAP will create the external group record once it has been learned from the AAA system.

To manage groups within IAP:

1. Login to IAP as Administrator (a User with the Pronghorn.admin Role).
2. Navigate to Settings > Authorization.
3. Select the Groups tab. A list of all defined groups and their provenances is displayed.
4. Locate the Group in the list.
   • Filter the list by typing in the Search Groups field.
5. Select the Group in the list to view or edit.
6. Edit the description, as desired.
7. Edit Roles and Groups, as desired.
8. Click Save to finalize changes.

Configuring Group Membership

An IAP group may be added or removed using the Authorization Manager. IAP groups and external groups can be given membership to an IAP group. In contrast, neither group can be given membership to an external group.

To change group membership:

1. Login to IAP as Administrator (a User with the Pronghorn.admin Role).
2. Navigate to Settings > Authorization.
3. Select the Groups tab. A list of defined groups is displayed.
4. Locate the Group in the list.
   • Filter the list by typing in the Search Groups field.
5. Select the Group in the list to view or edit.
6. From the Edit Group canvas, select the Groups tab.
7. Add or remove Group membership by selecting the checkbox.

Identifying Group Members

A members list identifies the users and groups that are direct members of a group.

1. Navigate to the Group edit screen.
2. Locate the Members list (right side of screen).
   • Inherited memberships are not indicated.

Deleting a Group

WARNING: This is a hard delete. Deleting a Group will remove the Role from all Users and Groups assigned to it.

Only IAP groups can be deleted.

1. Select the Group.
2. Click the Delete button.
3. Confirm the deletion.

Alternate method:

1. Click the View List icon in the Groups header to access the Groups table view.
2. Locate the Group you wish to delete.
   • Filter the list using the filter fields in the column header.
3. Click the Delete button for the Group.
4. Confirm the deletion.

Roles

A role is a bundle of permissions assigned to users and/or groups. Roles are defined in the pronghorn.json for each application and assigned to methods/tasks and views with the “roles” property. With IAP, you now have the ability to define Custom Roles for your installation.

Built-In Roles

• admin
• apiread
• apiwrite
• support
• operations/operator
• engineering
• taskread
• taskwrite
• authorization

Endpoints

A role grants permission to access one or more endpoints. Endpoints are defined by the applications and IAP. There are essentially two types of endpoints.

Endpoint Type	Description
Methods	Represent API Endpoints that read or write data.
Views	Represent web pages in the browser. A View will typically rely on one or more Methods to read and write data.

A role may be assigned to any number of users or groups. This provides access to all endpoints granted to the role. The final permission set for a user is a combination of permissions granted to all the roles assigned to a user, or to any groups in which the user is a member.

Managing Roles

In addition to built-in roles defined by applications, IAP allows administrators to define Custom Roles for an installation to allow for least privilege. Built-in roles are hardcoded in the applications (or in IAP) and are not user-editable.

To manage roles within IAP:

1. Login as Administrator (a User with the Pronghorn.admin Role).
2. Navigate to Settings > Authorization.
3. Select the Roles tab. A sectioned list displays.
   • There is a section for each Application installed in the system.
   • If any Custom Roles have been defined, a Custom section also appears.
4. Expand a section to display the Roles defined within it.
5. Select a Role to open it for viewing or editing.
6. Click Save to finalize any changes.
7. Click the View List icon in the Roles header to show an advanced table view.
   • You can view all Roles in a single list.
   • You can filter and/or sort Roles using various fields.

Configuring Role Assignments

Groups are assigned to roles in two ways:

• Directly.
• By membership in another group.

To assign roles directly to a group in IAP:

1. In the left-side navigation panel, select the Groups tab.
2. Select a Group to open it for viewing or editing.
3. In the Edit Group canvas, locate the Role you wish to assign.
   • Filter the list by typing in the Role or Source text box.
4. Add or Remove a Role assignment by selecting the checkbox.

Roles which are assigned by other groups are greyed out (disabled). This indicates the assignment is inherited.

Inspecting a Built-In Role

To inspect a built-in role:

1. In the left-side navigation panel, select the Roles tab.
2. Click the View List icon in the Roles header to show the Roles table view.
3. Optionally type a column filter.
4. Click the Inspect Role icon next to a Role to show the list of all Endpoints granted to the Role.

Creating a Custom Role

Use a unique name when creating a custom role.

1. Click the Add New Role icon in the Role header.
2. Give the new custom role a name (required).
3. Give the new custom role a description (optional).
4. Edit permissions (optional). Refer to Managing Custom Role Permissions below.
5. Click Save to finalize your changes.

Editing a Custom Role

Only custom roles may be edited.

1. In the left-side navigation panel, select the Roles tab.
2. Expand the Custom section or optionally type the name of the Role in the Search Roles field.
   • Select the desired Role from the results list.
   • Update the Role name, if needed.
   • Update the Role description, if needed.
   • Edit permissions (optional). Refer to Managing Custom Role Permissions below.
   • Click Save to finalize your changes.
3. Alternatively, click the View List icon in the Roles header to open the Roles table view.
   • Optionally type a column filter.
   • Click the Edit Role icon next to a Custom Role.
   • Update the Role name, if needed.
   • Update the Role description, if needed.
   • Edit permissions (optional). Refer to Managing Custom Role Permissions below.
   • Click Save to finalize your changes.

Managing Custom Role Permissions

Custom role permissions are managed in two ways: simple view or advanced view.

Simple View

1. Type the name of an installed Application in the Application field.
2. Select the Application from the results list.
   • The Application will be added to the Application table and selected for editing.
   • The Endpoints for the selected Application will display in the Detail panel, with tabs for Methods and Views, respectively.
3. Locate the Endpoint you would like to grant or remove.
   • Filter the list by typing in the header text box.
4. Use one of the following to Add or Remove permitted Endpoints:
   • Add or Remove by selecting the checkbox
   • Use the header checkbox to Select All / Deselect All.

Advanced View

1. Click Advanced next to the Application field.
2. Locate the Endpoint you would like to grant or remove.
   • Filter the list by typing in the headers of the Endpoints tables.
3. Add or Remove permitted Endpoints by selecting the checkbox.

Deleting a Custom Role

WARNING: This is a hard delete. Deleting a Custom Role will remove references to the Role from all Users and Groups assigned to it.

As with any other modifications, only custom roles may be deleted.

1. In the left-side navigation panel, click the View List icon in the Roles header to access the Roles table view.
2. Locate the Custom Role you wish to delete.
   Filter the list using the Filter fields in the column header.
3. Click the Delete button for the Role.
4. Confirm the deletion.

Custom Applications and Built-In Roles

Applications define Built-In Roles along with Endpoints in pronghorn.json. The following excerpt from a pronghorn.json file is provided as an example.

{
    "roles": [
        "admin",
        "engineering",
        "support",
        "apiread",
        "authorization"
    ],
    "methods": [
        {
            "name": "getTasksList",
            "roles": [
                "admin",
                "engineering",
                "support"
            ]
        }
    ],
    "views": [
        {
            "path": "/edit",
            "roles": [
                "admin",
                "engineering"
            ]
        }
    ]
}

In the preceding example, the Application defines five (5) Built-In Roles. The getTasksList Method is granted to three of them. In contrast, the /edit View is granted to only two.

The declarations will be ingested at application load time and cached in the IAP database to assist with various queries. At application load time, the roles that are cached for the application will be replaced with the roles and permissions defined in pronghorn.json.

If pronghorn.json is inconsistent in its role names, warnings will appear in the IAP logs at application load time.

Note: If an application is upgraded and the new version no longer declares a Role, it will be deleted and references to it will be removed from all Users and Groups. Additionally, role names are the identifier for application Roles. Renaming a role is effectively the same as deleting it and declaring a new one. In each case, some users may lose access to your application. Therefore, removal or renaming of existing Roles is considered a breaking change.

Application Roles by API Method, Task and View

The charts in this section show the default roles found in pronghorn.json for each application as delivered.

Note: These charts will change based on the version of IAP that is running. Therefore, as a best practice, Itential recommends that you review the APIs, application Roles and their respective permissions for the latest information. You can view this in the Itential UI by navigating to the Authorization Manager page and selecting Roles (IAP > Settings > Authorization > Roles).

Device Manager

API Method/Task	admin	apiread	apiwrite	engineering	operations
addDevice	x		x
addDevicesToDeviceGroup	x		x
addToAuthGroup	x		x
addToDeviceGroup	x		x
applyVariableTemplateDevices	x		x
backupDeviceConfig	x		x
checkSyncDevices	x	x
createDeviceGroup	x		x
deleteDevice	x		x
deleteDeviceBackups	x
diff	x	x
diffByID	x	x
diffToHtml	x	x
dryRunVariableTemplateDevices	x	x
getAuthGroups	x	x
getDevice	x	x
getDeviceAuthgroup	x	x
getDeviceBackups	x
getDeviceConfig	x	x
getDeviceGroup	x	x
getDeviceGroups	x	x
getDeviceGroupsForDevice	x	x
getDeviceGroupsForDevices	x	x
getDevices	x	x
getNeds	x	x
getOutOfSyncConfig	x	x
getTemplates	x	x
removeFromDeviceGroup	x		x
syncFrom	x		x
syncTo	x		x

	View	admin	engineering	operations
Add Device Form Task	/task/addDeviceForm	x
CLI Dialog	/dialog/cli	x	x	x
Config Dialog	/dialog/config	x	x	x
Delete Backup Dialog	/dialog/deleteBackup	x	x	x
Device Management	/device_config	x	x	x
Edit Device Dialog	/dialog/editDevice	x	x	x
Selected Device Dialog	/dialog/syncDevice	x	x	x
Selected Device Dialog	/selectedDevice	x	x	x
Selected Device Fault Information Dialog	/dialog/selectedDeviceFault	x	x	x

Form Builder

API Method/Task	admin	apiread	apiwrite	operator
deleteForm	x		x
fetchdata	x		x	x
getElementDefinition	x	x		x
getForm	x	x		x
getFormByName	x	x		x
listElements	x	x		x
listForms	x	x		x
renderForm	x	x		x
saveForm	x		x

	View	admin	engineering	operations
Clone	/clone	x
Form	/form	x
Form Builder	/	x
Form Builder	/edit	x
Show Form By Name Task	/task/showFormByName	x		x
TEST	/form_partial	x

MOP

API Method/Task	admin	apiread	apiwrite	engineering	support
GetBootFlash	x	x		x	x
RunCommand	x		x
RunCommandDevices	x		x
RunCommandTemplate	x		x
RunCommandTemplateSingleCommand	x		x
SetBoot	x		x
createAnalyticTemplate	x		x
createTemplate	x		x
deleteAnalyticTemplate	x		x
deleteTemplate	x		x
getDevicesFiltered	x			x	x
listATemplate	x	x		x	x
listAnAnalyticTemplate	x	x		x	x
listAnalyticTemplates	x	x		x	x
listTemplates	x	x		x	x
passThru	x		x
ping	x	x		x	x
reattempt	x		x	x	x
runAnalyticsTemplate	x		x	x	x
updateAnalyticTemplate	x		x
updateTemplate	x		x

	View	admin	engineering	support
Choose Device Task	/task/chooseDevice	x	x	x
MOP	/	x
MOP Analytic Template	/analytic	x	x	x
MOP Decision Task	/task/decisionTask	x	x	x
MOP Diff Config	/task/diffConfig	x	x	x
MOP Diff Template	/task/runTemplatesDiff	x	x	x
MOP Manual Task	/task/reloadFailed	x	x	x
MOP Review Summary	/task/reviewSummary	x	x	x
MOP Template	/template	x	x	x
MOP Verify Config	/task/verifyConfig	x	x	x
MOP Confirm Task	/task/confirmTask	x	x	x
Variable Selector	/modals/variableSelector	x	x	x
View MOP Template Results	/task/viewTemplateResults	x	x	x

NSO Manager

API Method/Task	admin	other
addLockItem	x
applyTemplates	x
deleteQueueItem	x
getCommitQueueDeep	x
getQueueItemDetails	x
getQueuedDevices	x
liveStatus	x
lockQueueItem	x
pruneDevicesAllItems	x
pruneDevicesFromItem	x
runAction	x
setItemNacmGroup	x
setLeaf	x
unlockQueueItem	x
verifyConfig	x	x

	View	admin
Commit Queue Manager	/commit_queue_manager	x
Ned Validator	/ned_inspector	x
Set Device Configuration	/task/SetDeviceConfiguration	x
User creates list of devices from a given list of device options	/modal/devicePicker	x
View queue item details	/modal/itemDetails	x

Service Catalog

API Method/Task	admin	apiread	apiwrite	engineering	support
AddNewServiceToCatalog	x		x	x	x
GetFormData	x	x		x	x
GetFormId	x	x		x	x
GetForms	x	x		x	x
GetUserObject	x	x		x	x
GetWorkflows	x	x		x	x
ServiceCatalogStore	x	x		x	x
ServiceModels	x	x		x	x
UpdateServiceInCatalog	x		x	x	x
deleteService	x		x	x	x
getGroups	x	x		x	x

	View	admin	engineering	operations
Add Service	/addService	x	x
Service Catalog	/	x	x	x
Service Catalog Builder	/manage	x	x
Service Catalog Builder	/edit	x	x

Service Manager

API Method/Task	admin	apiread	apiwrite	engineering	support
checkSync	x	x		x	x
config	x	x		x	x
createServiceModelForm	x		x	x	x
deleteInstances	x		x	x	x
deleteServiceModelFromDatabase	x		x	x	x
deleteServicePathsDryRun	x	x		x	x
deviceModifications	x	x		x	x
getDevicesInServiceInstance	x	x		x	x
getInstance	x	x
getInstancesOfService	x	x		x	x
getServiceInstanceMap	x	x		x	x
getServiceModel	x	x		x	x
getServiceModelMap	x	x		x	x
getServicesDetails	x	x		x	x
listServiceModels	x	x		x	x
reactiveRedeploy	x		x	x	x
saveInstances	x		x	x	x
testInstances	x	x		x	x

	View	admin	engineering	operations	taskread	taskwrite
Device Config	/deviceConfigDialog	x	x	x
Dry Run	/dryRunDialog	x	x	x
Out of Syncn	/outOfSyncDialog	x	x	x
Service Manager	/list	x	x
Service Manager	/instances	x	x
Service Manager	/view	x	x
Service Manager	/cloned_form	x	x
Service Manager	/form	x	x
Service Manager	/edit	x	x
View Dry Run Results	/task/ViewTestService	x			x
View Service Model	/task/ViewServiceModelForm	x			x

Workflow Builder

API Method/Task	admin	apiread	authorization	engineering	support
buildTaskTemplate	x			x	x
createWorkflowGroupEntry			x
deleteWorkflow	x			x	x
deleteWorkflowGroups			x
filterTasksByEntity	x			x	x
getJobsOfWorkflow	x			x	x
getPreviousTasks	x			x	x
getTaskDetails	x			x	x
getTasksList	x			x	x
getWorkflowVisualizationData	x			x	x
getWorkflowsFiltered	x			x	x
getWorkflowsList	x			x	x
listWorkflowGroups		x	x
removeWorkflowGroup			x
replaceWorkflowGroups			x
saveWorkflow	x			x	x

	View	admin	engineering
Add New Job Variable	/editNewVariable	x	x
Clone Workflow	/dialog/cloneWorkflow	x	x
Create Workflow	/dialog/createWorkflow	x	x
Edit Child Job	/editChildJob	x	x
Edit Deep Merge	/editDeepMerge	x	x
Edit Eval	/editEval	x	x
Edit Merge	/editMerge	x	x
Edit Push	/editPush	x	x
Edit Shift or Pop	/editShiftPop	x	x
Edit Task	/editTask	x	x
Edit Transition	/editTransition	x	x
Job Description	/dialog/jobDescription	x	x
Reference Warning	/referenceWarn	x	x
Select Task	/dialog/selectTask	x	x
Set Variables	/dialog/setVariables	x	x
Test Task	/task/TestTask	x
Workflow Builder	/home	x	x
Workflow Builder	/edit	x	x
Workflow Builder	/	x	x
Workflow Settings	/dialog/workflowSettings	x	x

Workflow Engine

API Method/Task	admin	apiread	authorization	engineering	support
addWatchers	x		x
canceljob	x		x		x
checkWorkflowForJobVariables	x	x			x
childJob	x		x
claimJob	x	x	x		x
claimTask	x	x	x		x
createJobGroupEntry				x
deepmerge	x		x
delay	x		x
deleteJobGroups				x
evaluation	x	x
find	x	x
findForwardPaths	x	x			x
fixJob	x		x
forEach	x		x
getAllLoopTasks	x	x
getAssociatedJobs	x	x
getCompletedJobs	x	x
getEntireJob	x	x
getJob	x	x
getJobDeep	x	x
getJobFromTaskQuery	x	x
getJobList	x	x
getJobShallow	x	x
getJobVisualizationData	x	x			x
getManualTaskController	x	x			x
getTask	x	x
getTaskIterations	x	x
getTaskStatuses	x	x			x
getWorkflowsDetailedByName	x	x			x
listJobGroups		x		x
merge	x		x
modify	x		x
newVariable	x		x
pauseJob	x		x
pop	x		x
push	x		x
query	x	x
queryJobs	x	x
queryTasks	x	x
queryTasksBrief	x	x
releaseJob	x	x	x		x
releaseTask	x	x	x		x
removeJobGroup				x
replaceJobGroups				x
resumeJob	x		x
returnCompletedTaskData	x	x			x
revertToTask	x		x
runEvaluation	x		x
runEvaluationGroup	x		x
runEvaluationGroups	x		x
searchTasks	x	x
shift	x		x
startjob	x		x		x
startJobWithOptions	x		x		x
unwatchJob	x		x
updateJobDescription	x		x
validateAllLoops	x	x
watchJob	x		x

	View	admin	engineering	operations
Active Jobs	/jobs	x	x
Active Tasks	/	x	x
Job Manager	/manager	x
Job Viewer	/job	x	x
Review Job Errors	/dialog/JobErrors	x	x	x
Review Task Details	/dialog/TaskReview	x	x	x
Review Task Options	/dialog/TaskOptions	x	x	x
Task Manager	/task_manager	x